home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tk / ConfigWind.man < prev    next >
Encoding:
Text File  |  1992-08-24  |  8.9 KB  |  317 lines
  1. '\"
  2. '\" Copyright 1990 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/wish/man/RCS/ConfigWind.man,v 1.8 92/04/18 14:03:00 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS Tk_ConfigureWindow tk
  189. .BS
  190. .SH NAME
  191. .na
  192. Tk_ConfigureWindow, Tk_MoveWindow, Tk_ResizeWindow, Tk_MoveResizeWindow, Tk_SetWindowBorderWidth Tk_ChangeWindowAttributes, Tk_SetWindowBackground, Tk_SetWindowBackgroundPixmap, Tk_SetWindowBorder, Tk_SetWindowBorderPixmap, Tk_DefineCursor, Tk_UndefineCursor \- change window configuration or attributes
  193. .ad
  194. .SH SYNOPSIS
  195. .nf
  196. \fB#include <tk.h>\fR
  197. .sp
  198. \fBTk_ConfigureWindow\fR(\fItkwin, valueMask, valuePtr\fR)
  199. .sp
  200. \fBTk_MoveWindow\fR(\fItkwin, x, y\fR)
  201. .sp
  202. \fBTk_ResizeWindow\fR(\fItkwin, width, height\fR)
  203. .sp
  204. \fBTk_MoveResizeWindow\fR(\fItkwin, x,  y, width, height\fR)
  205. .sp
  206. \fBTk_SetWindowBorderWidth\fR(\fItkwin, borderWidth\fR)
  207. .sp
  208. \fBTk_ChangeWindowAttributes\fR(\fItkwin, valueMask, attsPtr\fR)
  209. .sp
  210. \fBTk_SetWindowBackground\fR(\fItkwin, pixel\fR)
  211. .sp
  212. \fBTk_SetWindowBackgroundPixmap\fR(\fItkwin, pixmap\fR)
  213. .sp
  214. \fBTk_SetWindowBorder\fR(\fItkwin, pixel\fR)
  215. .sp
  216. \fBTk_SetWindowBorderPixmap\fR(\fItkwin, pixmap\fR)
  217. .sp
  218. .VS
  219. \fBTk_DefineCursor\fR(\fItkwin, cursor\fR)
  220. .sp
  221. \fBTk_UndefineCursor\fR(\fItkwin\fR)
  222. .VE
  223. .SH ARGUMENTS
  224. .AS XSetWindowAttributes borderWidth
  225. .AP Tk_Window tkwin in
  226. Token for window.
  227. .AP "unsigned int" valueMask in
  228. OR-ed mask of values like \fBCWX\fR or \fBCWBorderPixel\fR,
  229. indicating which fields of \fI*valuePtr\fR or \fI*attsPtr\fR to use.
  230. .AP XWindowChanges *valuePtr in
  231. Points to a structure containing new values for the configuration
  232. parameters selected by \fIvalueMask\fR.  Fields not selected
  233. by \fIvalueMask\fR are ignored.
  234. .AP int x in
  235. New x-coordinate for \fItkwin\fR's top left pixel (including
  236. border, if any) within tkwin's parent.
  237. .AP int y in
  238. New y-coordinate for \fItkwin\fR's top left pixel (including
  239. border, if any) within tkwin's parent.
  240. .AP "unsigned int" width in
  241. New width for \fItkwin\fR (interior, not including border).
  242. .AP "unsigned int" height in
  243. New height for \fItkwin\fR (interior, not including border).
  244. .AP "unsigned int" borderWidth in
  245. New width for \fItkwin\fR's border.
  246. .AP XSetWindowAttributes *attsPtr in
  247. Points to a structure containing new values for the attributes
  248. given by the \fIvalueMask\fR argument.  Attributes not selected
  249. by \fIvalueMask\fR are ignored.
  250. .AP "unsigned long" pixel in
  251. New background or border color for window.
  252. .AP Pixmap pixmap in
  253. New pixmap to use for background or border of \fItkwin\fR.  WARNING:
  254. cannot necessarily be deleted immediately, as for Xlib calls.  See
  255. note below.
  256. .AP Cursor cursor in
  257. .VS
  258. New cursor to use for \fItkwin\fR.  If \fBNone\fR is specified, then
  259. \fItkwin\fR will not have its own cursor;  it will use the cursor
  260. of its parent.
  261. .VE
  262. .BE
  263.  
  264. .SH DESCRIPTION
  265. .PP
  266. These procedures are analogous to the X library procedures
  267. with similar names, such as \fBXConfigureWindow\fR.  Each
  268. one of the above procedures calls the corresponding X procedure
  269. and also saves the configuration information in Tk's local
  270. structure for the window.  This allows the information to
  271. be retrieved quickly by the application (using macros such
  272. as \fBTk_X\fR and \fBTk_Height\fR) without having to contact
  273. the X server.  In addition, if no X window has actually been
  274. created for \fItkwin\fR yet, these procedures do not issue
  275. X operations or cause event handlers to be invoked;  they save
  276. the information in Tk's local
  277. structure for the window;  when the window is created later,
  278. the saved information will be used to configure the window.
  279. .PP
  280. See the X library documentation for details on what these
  281. procedures do and how they use their arguments.
  282. .PP
  283. In the procedures \fBTk_ConfigureWindow\fR, \fBTk_MoveWindow\fR,
  284. \fBTk_ResizeWindow\fR, \fBTk_MoveResizeWindow\fR, and
  285. \fBTk_SetWindowBorderWidth\fR,
  286. if \fItkwin\fR is a child window (i.e. it was created with a call
  287. to \fBTk_CreateChildWindow\fR), then event handlers interested
  288. in configure events
  289. are invoked immediately.  If \fItkwin\fR isn't an internal window,
  290. then the event handlers will be invoked later, after X has seen
  291. the request and returned an event for it.
  292. .PP
  293. Applications using Tk should never call procedures like
  294. \fBXConfigureWindow\fR directly;  they should always use the
  295. corresponding Tk procedures.
  296.  
  297. .SH BUGS
  298. .PP
  299. \fBTk_SetWindowBackgroundPixmap\fR and \fBTk_SetWindowBorderPixmap\fR
  300. differ slightly from their Xlib counterparts in that the \fIpixmap\fR
  301. argument may not necessarily be deleted immediately after calling
  302. one of these procedures.  This is because \fItkwin\fR's window
  303. may not exist yet at the time of the call, in which case \fIpixmap\fR
  304. is merely saved and used later when \fItkwin\fR's window is actually
  305. created.  If you wish to delete \fIpixmap\fR, then call
  306. \fBTk_MakeWindowExist\fR first to be sure that \fItkwin\fR's window exists
  307. and \fIpixmap\fR has been passed to the X server.
  308. .PP
  309. .VS
  310. A similar problem occurs for the \fIcursor\fR argument passed to
  311. \fBTk_DefineCursor\fR.  The solution is the same as for pixmaps above:
  312. call \fBTk_MakeWindowExist\fR before freeing the cursor.
  313. .VE
  314.  
  315. .SH KEYWORDS
  316. attributes, border, color, configure, height, pixel, pixmap, width, window, x, y
  317.